List items
A list marker is a bullet list marker or an ordered list marker.
A bullet list marker is a -, +, or * character.
An ordered list marker is a sequence of 1–9 arabic digits (0-9), followed by either a . character or a )character. (The reason for the length limit is that with 10 digits we start seeing integer overflows in some browsers.)
The following rules define list items:
- Basic case. If a sequence of lines Ls constitute a sequence of blocks Bs starting with a [non-whitespace character], and M is a list marker of width W followed by 1 ≤ N ≤ 4 spaces, then the result of prepending M and the following spaces to the first line of Ls, and indenting subsequent lines of Ls by W + N spaces, is a list item with Bs as its contents. The type of the list item (bullet or ordered) is determined by the type of its list marker.
Exceptions:- When the first list item in a list interrupts a paragraph—that is, when it starts on a line that would otherwise count as paragraph continuation text—then (a) the lines Ls must not begin with a blank line, and (b) if the list item is ordered, the start number must be 1.
- If any line is a thematic break then that line is not a list item.
For example, let Ls be the lines
Example 231
| Markdown | HTML | Demo |
|---|---|---|
| |
And let M be the marker 1., and N = 2. Then rule #1 says that the following is an ordered list item with start number 1, and the same contents as Ls:
Example 232
| Markdown | HTML | Demo |
|---|---|---|
| |
The most important thing to notice is that the position of the text after the list marker determines how much indentation is needed in subsequent blocks in the list item. If the list marker takes up two spaces, and there are three spaces between the list marker and the next non-whitespace character, then blocks must be indented five spaces in order to fall under the list item.
Here are some examples showing how far content must be indented to be put under the list item:
Example 233
| Markdown | HTML | Demo |
|---|---|---|
| |
Example 234
| Markdown | HTML | Demo |
|---|---|---|
| |
Example 235
| Markdown | HTML | Demo |
|---|---|---|
| |
Example 236
| Markdown | HTML | Demo |
|---|---|---|
| |
It is tempting to think of this in terms of columns: the continuation blocks must be indented at least to the column of the first non-whitespace character after the list marker. However, that is not quite right. The spaces after the list marker determine how much relative indentation is needed. Which column this indentation reaches will depend on how the list item is embedded in other constructions, as shown by this example:
Example 237
| Markdown | HTML | Demo |
|---|---|---|
| |
Here two occurs in the same column as the list marker 1., but is actually contained in the list item, because there is sufficient indentation after the last containing blockquote marker.
The converse is also possible. In the following example, the word two occurs far to the right of the initial text of the list item, one, but it is not considered part of the list item, because it is not indented far enough past the blockquote marker:
Example 238
| Markdown | HTML | Demo |
|---|---|---|
| |
Note that at least one space is needed between the list marker and any following content, so these are not list items:
Example 239
| Markdown | HTML | Demo |
|---|---|---|
| |
A list item may contain blocks that are separated by more than one blank line.
Example 240
| Markdown | HTML | Demo |
|---|---|---|
| |
A list item may contain any kind of block:
Example 241
| Markdown | HTML | Demo |
|---|---|---|
| |
A list item that contains an indented code block will preserve empty lines within the code block verbatim.
Example 242
| Markdown | HTML | Demo |
|---|---|---|
| |
Note that ordered list start numbers must be nine digits or less:
Example 243
| Markdown | HTML | Demo |
|---|---|---|
| |
Example 244
| Markdown | HTML | Demo |
|---|---|---|
| |
A start number may begin with 0s:
Example 245
| Markdown | HTML | Demo |
|---|---|---|
| |
Example 246
| Markdown | HTML | Demo |
|---|---|---|
| |
A start number may not be negative:
Example 247
| Markdown | HTML | Demo |
|---|---|---|
| |
- Item starting with indented code. If a sequence of lines Ls constitute a sequence of blocks _Bs_starting with an indented code block, and M is a list marker of width W followed by one space, then the result of prepending M and the following space to the first line of Ls, and indenting subsequent lines of Ls by W + 1 spaces, is a list item with Bs as its contents. If a line is empty, then it need not be indented. The type of the list item (bullet or ordered) is determined by the type of its list marker. If the list item is ordered, then it is also assigned a start number, based on the ordered list marker.
An indented code block will have to be indented four spaces beyond the edge of the region where text will be included in the list item. In the following case that is 6 spaces:
Example 248
| Markdown | HTML | Demo |
|---|---|---|
| |
And in this case it is 11 spaces:
Example 249
| Markdown | HTML | Demo |
|---|---|---|
| |
If the first block in the list item is an indented code block, then by rule #2, the contents must be indented _one_space after the list marker:
Example 250
| Markdown | HTML | Demo |
|---|---|---|
| |
Example 251
| Markdown | HTML | Demo |
|---|---|---|
| |
Note that an additional space indent is interpreted as space inside the code block:
Example 252
| Markdown | HTML | Demo |
|---|---|---|
| |
Note that rules #1 and #2 only apply to two cases: (a) cases in which the lines to be included in a list item begin with a non-whitespace character, and (b) cases in which they begin with an indented code block. In a case like the following, where the first block begins with a three-space indent, the rules do not allow us to form a list item by indenting the whole thing and prepending a list marker:
Example 253
| Markdown | HTML | Demo |
|---|---|---|
| |
Example 254
| Markdown | HTML | Demo |
|---|---|---|
| |
This is not a significant restriction, because when a block begins with 1-3 spaces indent, the indentation can always be removed without a change in interpretation, allowing rule #1 to be applied. So, in the above case:
Example 255
| Markdown | HTML | Demo |
|---|---|---|
| |
- Item starting with a blank line. If a sequence of lines Ls starting with a single blank line constitute a (possibly empty) sequence of blocks Bs, not separated from each other by more than one blank line, and M is a list marker of width W, then the result of prepending M to the first line of Ls, and indenting subsequent lines of Ls by W + 1 spaces, is a list item with Bs as its contents. If a line is empty, then it need not be indented. The type of the list item (bullet or ordered) is determined by the type of its list marker. If the list item is ordered, then it is also assigned a start number, based on the ordered list marker.
Here are some list items that start with a blank line but are not empty:
Example 256
| Markdown | HTML | Demo |
|---|---|---|
| |
When the list item starts with a blank line, the number of spaces following the list marker doesn’t change the required indentation:
Example 257
| Markdown | HTML | Demo |
|---|---|---|
| |
A list item can begin with at most one blank line. In the following example, foo is not part of the list item:
Example 258
| Markdown | HTML | Demo |
|---|---|---|
| |
Here is an empty bullet list item:
Example 259
| Markdown | HTML | Demo |
|---|---|---|
| |
It does not matter whether there are spaces following the list marker:
Example 260
| Markdown | HTML | Demo |
|---|---|---|
| |
Here is an empty ordered list item:
Example 261
| Markdown | HTML | Demo |
|---|---|---|
| |
A list may start or end with an empty list item:
Example 262
| Markdown | HTML | Demo |
|---|---|---|
| |
However, an empty list item cannot interrupt a paragraph:
Example 263
| Markdown | HTML | Demo |
|---|---|---|
| |
- Indentation. If a sequence of lines Ls constitutes a list item according to rule #1, #2, or #3, then the result of indenting each line of Ls by 1-3 spaces (the same for each line) also constitutes a list item with the same contents and attributes. If a line is empty, then it need not be indented.
Indented one space:
Example 264
| Markdown | HTML | Demo |
|---|---|---|
| |
Indented two spaces:
Example 265
| Markdown | HTML | Demo |
|---|---|---|
| |
Indented three spaces:
Example 266
| Markdown | HTML | Demo |
|---|---|---|
| |
Four spaces indent gives a code block:
Example 267
| Markdown | HTML | Demo |
|---|---|---|
| |
- Laziness. If a string of lines Ls constitute a list item with contents Bs, then the result of deleting some or all of the indentation from one or more lines in which the next non-whitespace character after the indentation is paragraph continuation text is a list item with the same contents and attributes. The unindented lines are called lazy continuation lines.
Here is an example with lazy continuation lines:
Example 268
| Markdown | HTML | Demo |
|---|---|---|
| |
Indentation can be partially deleted:
Example 269
| Markdown | HTML | Demo |
|---|---|---|
| |
These examples show how laziness can work in nested structures:
Example 270
| Markdown | HTML | Demo |
|---|---|---|
| |
Example 271
| Markdown | HTML | Demo |
|---|---|---|
| |
- That’s all. Nothing that is not counted as a list item by rules #1–5 counts as a list item.
The rules for sublists follow from the general rules above. A sublist must be indented the same number of spaces a paragraph would need to be in order to be included in the list item.
So, in this case we need two spaces indent:
Example 272
| Markdown | HTML | Demo |
|---|---|---|
| |
One is not enough:
Example 273
| Markdown | HTML | Demo |
|---|---|---|
| |
Here we need four, because the list marker is wider:
Example 274
| Markdown | HTML | Demo |
|---|---|---|
| |
Three is not enough:
Example 275
| Markdown | HTML | Demo |
|---|---|---|
| |
A list may be the first block in a list item:
Example 276
| Markdown | HTML | Demo |
|---|---|---|
| |
Example 277
| Markdown | HTML | Demo |
|---|---|---|
| |
A list item can contain a heading:
Example 278
| Markdown | HTML | Demo |
|---|---|---|
| |
5.2.1 Motivation
John Gruber’s Markdown spec says the following about list items:
- “List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.”
- “To make lists look nice, you can wrap items with hanging indents…. But if you don’t want to, you don’t have to.”
- “List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab.”
- “It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy.”
- “To put a blockquote within a list item, the blockquote’s
>delimiters need to be indented.” - “To put a code block within a list item, the code block needs to be indented twice — 8 spaces or two tabs.”
These rules specify that a paragraph under a list item must be indented four spaces (presumably, from the left margin, rather than the start of the list marker, but this is not said), and that code under a list item must be indented eight spaces instead of the usual four. They also say that a block quote must be indented, but not by how much; however, the example given has four spaces indentation. Although nothing is said about other kinds of block-level content, it is certainly reasonable to infer that all block elements under a list item, including other lists, must be indented four spaces. This principle has been called the four-space rule.
The four-space rule is clear and principled, and if the reference implementation Markdown.pl had followed it, it probably would have become the standard. However, Markdown.pl allowed paragraphs and sublists to start with only two spaces indentation, at least on the outer level. Worse, its behavior was inconsistent: a sublist of an outer-level list needed two spaces indentation, but a sublist of this sublist needed three spaces. It is not surprising, then, that different implementations of Markdown have developed very different rules for determining what comes under a list item. (Pandoc and python-Markdown, for example, stuck with Gruber’s syntax description and the four-space rule, while discount, redcarpet, marked, PHP Markdown, and others followed Markdown.pl’s behavior more closely.)
Unfortunately, given the divergences between implementations, there is no way to give a spec for list items that will be guaranteed not to break any existing documents. However, the spec given here should correctly handle lists formatted with either the four-space rule or the more forgiving Markdown.pl behavior, provided they are laid out in a way that is natural for a human to read.
The strategy here is to let the width and indentation of the list marker determine the indentation necessary for blocks to fall under the list item, rather than having a fixed and arbitrary number. The writer can think of the body of the list item as a unit which gets indented to the right enough to fit the list marker (and any indentation on the list marker). (The laziness rule, #5, then allows continuation lines to be unindented if needed.)
This rule is superior, we claim, to any rule requiring a fixed level of indentation from the margin. The four-space rule is clear but unnatural. It is quite unintuitive that
- foo
bar
- baz
should be parsed as two lists with an intervening paragraph,
<ul>
<li>foo</li>
</ul>
<p>bar</p>
<ul>
<li>baz</li>
</ul>
as the four-space rule demands, rather than a single list,
<ul>
<li>
<p>foo</p>
<p>bar</p>
<ul>
<li>baz</li>
</ul>
</li>
</ul>
The choice of four spaces is arbitrary. It can be learned, but it is not likely to be guessed, and it trips up beginners regularly.
Would it help to adopt a two-space rule? The problem is that such a rule, together with the rule allowing 1–3 spaces indentation of the initial list marker, allows text that is indented less than the original list marker to be included in the list item. For example, Markdown.pl parses
- one
two
as a single list item, with two a continuation paragraph:
<ul>
<li>
<p>one</p>
<p>two</p>
</li>
</ul>
and similarly
> - one
>
> two
as
<blockquote>
<ul>
<li>
<p>one</p>
<p>two</p>
</li>
</ul>
</blockquote>
This is extremely unintuitive.
Rather than requiring a fixed indent from the margin, we could require a fixed indent (say, two spaces, or even one space) from the list marker (which may itself be indented). This proposal would remove the last anomaly discussed. Unlike the spec presented above, it would count the following as a list item with a subparagraph, even though the paragraph bar is not indented as far as the first paragraph foo:
10. foo
bar
Arguably this text does read like a list item with bar as a subparagraph, which may count in favor of the proposal. However, on this proposal indented code would have to be indented six spaces after the list marker. And this would break a lot of existing Markdown, which has the pattern:
1. foo
indented code
where the code is indented eight spaces. The spec above, by contrast, will parse this text as expected, since the code block’s indentation is measured from the beginning of foo.
The one case that needs special treatment is a list item that starts with indented code. How much indentation is required in that case, since we don’t have a “first paragraph” to measure from? Rule #2 simply stipulates that in such cases, we require one space indentation from the list marker (and then the normal four spaces for the indented code). This will match the four-space rule in cases where the list marker plus its initial indentation takes four spaces (a common case), but diverge in other cases.